[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This chapter describes functions for manipulating dates and times, including functions for determining what the current time is and conversion between different time representations.
The time functions fall into three main categories:
1.1 Processor Time | Measures processor time used by a program. | |
1.2 Calendar Time | Manipulation of “real” dates and times. | |
1.3 Setting an Alarm | Sending a signal after a specified time. | |
1.4 Sleeping | Waiting for a period of time. | |
1.5 Resource Usage | Measuring various resources used. | |
1.6 Limiting Resource Usage | Specifying limits on resource usage. | |
1.7 Process Priority | Reading or setting process run priority. |
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
If you’re trying to optimize your program or measure its efficiency, it’s
very useful to be able to know how much processor time or CPU
time it has used at any given point. Processor time is different from
actual wall clock time because it doesn’t include any time spent waiting
for I/O or when some other process is running. Processor time is
represented by the data type clock_t
, and is given as a number of
clock ticks relative to an arbitrary base time marking the beginning
of a single program invocation.
1.1.1 Basic CPU Time Inquiry | The clock function.
| |
1.1.2 Detailed Elapsed CPU Time Inquiry | The times function.
|
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
To get the elapsed CPU time used by a process, you can use the
clock
function. This facility is declared in the header file
‘time.h’.
In typical usage, you call the clock
function at the beginning and
end of the interval you want to time, subtract the values, and then divide
by CLOCKS_PER_SEC
(the number of clock ticks per second), like this:
#include <time.h>
clock_t start, end;
double elapsed;
start = clock();
… /* Do the work. */
end = clock();
elapsed = ((double) (end - start)) / CLOCKS_PER_SEC;
Different computers and operating systems vary wildly in how they keep track of processor time. It’s common for the internal processor clock to have a resolution somewhere between hundredths and millionths of a second.
In the GNU system, clock_t
is equivalent to long int
and
CLOCKS_PER_SEC
is an integer value. But in other systems, both
clock_t
and the type of the macro CLOCKS_PER_SEC
can be
either integer or floating-point types. Casting processor time values
to double
, as in the example above, makes sure that operations
such as arithmetic and printing work properly and consistently no matter
what the underlying representation is.
The value of this macro is the number of clock ticks per second measured
by the clock
function.
This is an obsolete name for CLOCKS_PER_SEC
.
This is the type of the value returned by the clock
function.
Values of type clock_t
are in units of clock ticks.
This function returns the elapsed processor time. The base time is
arbitrary but doesn’t change within a single process. If the processor
time is not available or cannot be represented, clock
returns the
value (clock_t)(-1)
.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The times
function returns more detailed information about
elapsed processor time in a struct tms
object. You should
include the header file ‘sys/times.h’ to use this facility.
The tms
structure is used to return information about process
times. It contains at least the following members:
clock_t tms_utime
This is the CPU time used in executing the instructions of the calling process.
clock_t tms_stime
This is the CPU time used by the system on behalf of the calling process.
clock_t tms_cutime
This is the sum of the tms_utime
values and the tms_cutime
values of all terminated child processes of the calling process, whose
status has been reported to the parent process by wait
or
waitpid
; see @ref{Process Completion}. In other words, it represents
the total CPU time used in executing the instructions of all the terminated
child processes of the calling process.
clock_t tms_cstime
This is similar to tms_cutime
, but represents the total CPU time
used by the system on behalf of all the terminated child processes of the
calling process.
All of the times are given in clock ticks. These are absolute values; in a newly created process, they are all zero. @xref{Creating a Process}.
The times
function stores the processor time information for
the calling process in buffer.
The return value is the same as the value of clock()
: the elapsed
real time relative to an arbitrary base. The base is a constant within a
particular process, and typically represents the time since system
start-up. A value of (clock_t)(-1)
is returned to indicate failure.
Portability Note: The clock
function described in
Basic CPU Time Inquiry, is specified by the ANSI C standard. The
times
function is a feature of POSIX.1. In the GNU system, the
value returned by the clock
function is equivalent to the sum of
the tms_utime
and tms_stime
fields returned by
times
.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This section describes facilities for keeping track of dates and times according to the Gregorian calendar.
There are three representations for date and time information:
time_t
data type) is a compact
representation, typically giving the number of seconds elapsed since
some implementation-specific base time.
struct
timeval
data type) that includes fractions of a second. Use this time
representation instead of ordinary calendar time when you need greater
precision.
struct
tm
data type) represents the date and time as a set of components
specifying the year, month, and so on, for a specific time zone.
This time representation is usually used in conjunction with formatting
date and time values.
1.2.1 Simple Calendar Time | Facilities for manipulating calendar time. | |
1.2.2 High-Resolution Calendar | A time representation with greater precision. | |
1.2.3 Broken-down Time | Facilities for manipulating local time. | |
1.2.4 Formatting Date and Time | Converting times to strings. | |
1.2.5 Specifying the Time Zone with TZ | How users specify the time zone. | |
1.2.6 Functions and Variables for Time Zones | Functions to examine or specify the time zone. | |
1.2.7 Time Functions Example | An example program showing use of some of the time functions. |
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This section describes the time_t
data type for representing
calendar time, and the functions which operate on calendar time objects.
These facilities are declared in the header file ‘time.h’.
This is the data type used to represent calendar time. In the GNU C
library and other POSIX-compliant implementations, time_t
is
equivalent to long int
. When interpreted as an absolute time
value, it represents the number of seconds elapsed since 00:00:00 on
January 1, 1970, Coordinated Universal Time. (This date is sometimes
referred to as the epoch.)
In other systems, time_t
might be either an integer or
floating-point type.
The difftime
function returns the number of seconds elapsed
between time time1 and time time0, as a value of type
double
.
In the GNU system, you can simply subtract time_t
values. But on
other systems, the time_t
data type might use some other encoding
where subtraction doesn’t work directly.
The time
function returns the current time as a value of type
time_t
. If the argument result is not a null pointer, the
time value is also stored in *result
. If the calendar
time is not available, the value (time_t)(-1)
is returned.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The time_t
data type used to represent calendar times has a
resolution of only one second. Some applications need more precision.
So, the GNU C library also contains functions which are capable of representing calendar times to a higher resolution than one second. The functions and the associated data types described in this section are declared in ‘sys/time.h’.
The struct timeval
structure represents a calendar time. It
has the following members:
long int tv_sec
This represents the number of seconds since the epoch. It is equivalent
to a normal time_t
value.
long int tv_usec
This is the fractional second value, represented as the number of microseconds.
Some times struct timeval values are user for time intervals. Then the
tv_sec
member is the number of seconds in the interval, and
tv_usec
is the number of addictional microseconds.
The struct timezone
structure is used to hold minimal information
about the local time zone. It has the following members:
int tz_minuteswest
This is the number of minutes west of GMT.
int tz_dsttime
If nonzero, daylight savings time applies during some part of the year.
The struct timezone
type is obsolete and should never be used.
Instead, use the facilities described in Functions and Variables for Time Zones.
It is often necessary to subtract two values of type struct timeval
. Here is the best way to do this. It works even on some
peculiar operating systems where the tv_sec
member has an
unsigned type.
/* Subtract the `struct timeval' values X and Y,
storing the result in RESULT.
Return 1 if the difference is negative, otherwise 0. */
int
timeval_subtract (result, x, y)
struct timeval *result, *x, *y;
{
/* Perform the carry for the later subtraction by updating y. */
if (x->tv_usec < y->tv_usec) {
int nsec = (y->tv_usec - x->tv_usec) / 1000000 + 1;
y->tv_usec -= 1000000 * nsec;
y->tv_sec += nsec;
}
if (x->tv_usec - y->tv_usec > 1000000) {
int nsec = (y->tv_usec - x->tv_usec) / 1000000;
y->tv_usec += 1000000 * nsec;
y->tv_sec -= nsec;
}
/* Compute the time remaining to wait.
tv_usec
is certainly positive. */
result->tv_sec = x->tv_sec - y->tv_sec;
result->tv_usec = x->tv_usec - y->tv_usec;
/* Return 1 if result is negative. */
return x->tv_sec < y->tv_sec;
}
The gettimeofday
function returns the current date and time in the
struct timeval
structure indicated by tp. Information about the
time zone is returned in the structure pointed at tzp. If the tzp
argument is a null pointer, time zone information is ignored.
The return value is 0
on success and -1
on failure. The
following errno
error condition is defined for this function:
ENOSYS
The operating system does not support getting time zone information, and
tzp is not a null pointer. The GNU operating system does not
support using struct timezone
to represent time zone
information; that is an obsolete feature of 4.3 BSD.
Instead, use the facilities described in Functions and Variables for Time Zones.
The settimeofday
function sets the current date and time
according to the arguments. As for gettimeofday
, time zone
information is ignored if tzp is a null pointer.
You must be a privileged user in order to use settimeofday
.
The return value is 0
on success and -1
on failure. The
following errno
error conditions are defined for this function:
EPERM
This process cannot set the time because it is not privileged.
ENOSYS
The operating system does not support setting time zone information, and tzp is not a null pointer.
This function speeds up or slows down the system clock in order to make gradual adjustments in the current time. This ensures that the time reported by the system clock is always monotonically increasing, which might not happen if you simply set the current time.
The delta argument specifies a relative adjustment to be made to the current time. If negative, the system clock is slowed down for a while until it has lost this much time. If positive, the system clock is speeded up for a while.
If the olddelta argument is not a null pointer, the adjtime
function returns information about any previous time adjustment that
has not yet completed.
This function is typically used to synchronize the clocks of computers
in a local network. You must be a privileged user to use it.
The return value is 0
on success and -1
on failure. The
following errno
error condition is defined for this function:
EPERM
You do not have privilege to set the time.
Portability Note: The gettimeofday
, settimeofday
,
and adjtime
functions are derived from BSD.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Calender time is represented as a number of seconds. This is convenient for calculation, but has no resemblance to the way people normally represent dates and times. By contrast, broken-down time is a binary representation separated into year, month, day, and so on. Broken down time values are not useful for calculations, but they are useful for printing human readable time.
A broken-down time value is always relative to a choice of local time zone, and it also indicates which time zone was used.
The symbols in this section are declared in the header file ‘time.h’.
This is the data type used to represent a broken-down time. The structure contains at least the following members, which can appear in any order:
int tm_sec
This is the number of seconds after the minute, normally in the range
0
to 59
. (The actual upper limit is 61
, to allow
for “leap seconds”.)
int tm_min
This is the number of minutes after the hour, in the range 0
to
59
.
int tm_hour
This is the number of hours past midnight, in the range 0
to
23
.
int tm_mday
This is the day of the month, in the range 1
to 31
.
int tm_mon
This is the number of months since January, in the range 0
to
11
.
int tm_year
This is the number of years since 1900
.
int tm_wday
This is the number of days since Sunday, in the range 0
to 6
.
int tm_yday
This is the number of days since January 1, in the range 0
to
365
.
int tm_isdst
This is a flag that indicates whether Daylight Saving Time is (or was, or will be) in effect at the time described. The value is positive if Daylight Saving Time is in effect, zero if it is not, and negative if the information is not available.
long int tm_gmtoff
This field describes the time zone that was used to compute this
broken-down time value; it is the amount you must add to the local time
in that zone to get GMT, in units of seconds. The value is like that of
the variable timezone
(see section Functions and Variables for Time Zones). You can
also think of this as the “number of seconds west” of GMT. The
tm_gmtoff
field is a GNU library extension.
const char *tm_zone
This field is the three-letter name for the time zone that was used to compute this broken-down time value. It is a GNU library extension.
The localtime
function converts the calendar time pointed to by
time to broken-down time representation, expressed relative to the
user’s specified time zone.
The return value is a pointer to a static broken-down time structure, which might be overwritten by subsequent calls to any of the date and time functions. (But no other library function overwrites the contents of this object.)
Calling localtime
has one other effect: it sets the variable
tzname
with information about the current time zone. See section Functions and Variables for Time Zones.
This function is similar to localtime
, except that the broken-down
time is expressed as Coordinated Universal Time (UTC)—that is, as
Greenwich Mean Time (GMT) rather than relative to the local time zone.
Recall that calendar times are always expressed in coordinated universal time.
The mktime
function is used to convert a broken-down time structure
to a calendar time representation. It also “normalizes” the contents of
the broken-down time structure, by filling in the day of week and day of
year based on the other date and time components.
The mktime
function ignores the specified contents of the
tm_wday
and tm_yday
members of the broken-down time
structure. It uses the values of the other components to compute the
calendar time; it’s permissible for these components to have
unnormalized values outside of their normal ranges. The last thing that
mktime
does is adjust the components of the brokentime
structure (including the tm_wday
and tm_yday
).
If the specified broken-down time cannot be represented as a calendar time,
mktime
returns a value of (time_t)(-1)
and does not modify
the contents of brokentime.
Calling mktime
also sets the variable tzname
with
information about the current time zone. See section Functions and Variables for Time Zones.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The functions described in this section format time values as strings. These functions are declared in the header file ‘time.h’.
The asctime
function converts the broken-down time value that
brokentime points to into a string in a standard format:
"Tue May 21 13:46:22 1991\n"
The abbreviations for the days of week are: ‘Sun’, ‘Mon’, ‘Tue’, ‘Wed’, ‘Thu’, ‘Fri’, and ‘Sat’.
The abbreviations for the months are: ‘Jan’, ‘Feb’, ‘Mar’, ‘Apr’, ‘May’, ‘Jun’, ‘Jul’, ‘Aug’, ‘Sep’, ‘Oct’, ‘Nov’, and ‘Dec’.
The return value points to a statically allocated string, which might be overwritten by subsequent calls to any of the date and time functions. (But no other library function overwrites the contents of this string.)
The ctime
function is similar to asctime
, except that
the time value is specified in calendar time (rather than local time)
format. It is equivalent to
asctime (localtime (time))
ctime
sets the variable tzname
, because localtime
does so. See section Functions and Variables for Time Zones.
This function is similar to the sprintf
function (@pxref{Formatted
Input}), but the conversion specifications that can appear in the format
template template are specialized for printing components of the date
and time brokentime according to the locale currently specified for
time conversion (@pxref{Locales}).
Ordinary characters appearing in the template are copied to the output string s; this can include multibyte character sequences. Conversion specifiers are introduced by a ‘%’ character, and are replaced in the output string as follows:
%a
The abbreviated weekday name according to the current locale.
%A
The full weekday name according to the current locale.
%b
The abbreviated month name according to the current locale.
%B
The full month name according to the current locale.
%c
The preferred date and time representation for the current locale.
%d
The day of the month as a decimal number (range 01
to 31
).
%H
The hour as a decimal number, using a 24-hour clock (range 00
to
23
).
%I
The hour as a decimal number, using a 12-hour clock (range 01
to
12
).
%j
The day of the year as a decimal number (range 001
to 366
).
%m
The month as a decimal number (range 01
to 12
).
%M
The minute as a decimal number.
%p
Either ‘am’ or ‘pm’, according to the given time value; or the corresponding strings for the current locale.
%S
The second as a decimal number.
%U
The week number of the current year as a decimal number, starting with the first Sunday as the first day of the first week.
%W
The week number of the current year as a decimal number, starting with the first Monday as the first day of the first week.
%w
The day of the week as a decimal number, Sunday being 0
.
%x
The preferred date representation for the current locale, but without the time.
%X
The preferred time representation for the current locale, but with no date.
%y
The year as a decimal number, but without a century (range 00
to
99
).
%Y
The year as a decimal number, including the century.
%Z
The time zone or name or abbreviation (empty if the time zone can’t be determined).
%%
A literal ‘%’ character.
The size parameter can be used to specify the maximum number of
characters to be stored in the array s, including the terminating
null character. If the formatted time requires more than size
characters, the excess characters are discarded. The return value from
strftime
is the number of characters placed in the array s,
not including the terminating null character. If the value equals
size, it means that the array s was too small; you should
repeat the call, providing a bigger array.
If s is a null pointer, strftime
does not actually write
anything, but instead returns the number of characters it would have written.
For an example of strftime
, see Time Functions Example.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
TZ
In the GNU system, a user can specify the time zone by means of the
TZ
environment variable. For information about how to set
environment variables, see @ref{Environment Variables}. The functions for
accessing the time zone are declared in ‘time.h’.
The value of the TZ
variable can be of one of three formats. The
first format is used when there is no Daylight Saving Time (or summer
time) in the local time zone:
std offset
The std string specifies the name of the time zone. It must be three or more characters long and must not contain a leading colon or embedded digits, commas, or plus or minus signs. There is no space character separating the time zone name from the offset, so these restrictions are necessary to parse the specification correctly.
The offset specifies the time value one must add to the local time
to get a Coordinated Universal Time value. It has syntax like
[+
|-
]hh[:
mm[:
ss]]. This
is positive if the local time zone is west of the Prime Meridian and
negative if it is east. The hour must be between 0
and
24
, and the minute and seconds between 0
and 59
.
For example, here is how we would specify Eastern Standard Time, but without any daylight savings time alternative:
EST+5
The second format is used when there is Daylight Saving Time:
std offset dst [offset],
start[/
time],
end[/
time]
The initial std and offset specify the standard time zone, as described above. The dst string and offset specify the name and offset for the corresponding daylight savings time time zone; if the offset is omitted, it defaults to one hour ahead of standard time.
The remainder of the specification describes when daylight savings time is in effect. The start field is when daylight savings time goes into effect and the end field is when the change is made back to standard time. The following formats are recognized for these fields:
Jn
This specifies the Julian day, with n between 1
and 365
.
February 29 is never counted, even in leap years.
n
This specifies the Julian day, with n between 0
and 365
.
February 29 is counted in leap years.
Mm.w.d
This specifies day d of week w of month m. The day
d must be between 0
(Sunday) and 6
. The week
w must be between 1
and 5
; week 1
is the
first week in which day d occurs, and week 5
specifies the
last d day in the month. The month m should be
between 1
and 12
.
The time fields specify when, in the local time currently in
effect, the change to the other time occurs. If omitted, the default is
02:00:00
.
For example, here is how one would specify the Eastern time zone in the United States, including the appropriate daylight saving time and its dates of applicability. The normal offset from GMT is 5 hours; since this is west of the prime meridian, the sign is positive. Summer time begins on the first Sunday in April at 2:00am, and ends on the last Sunday in October at 2:00am.
EST+5EDT,M4.1.0/M10.5.0
The schedule of daylight savings time in any particular jurisdiction has changed over the years. To be strictly correct, the conversion of dates and times in the past should be based on the schedule that was in effect then. However, the system has no facilities to let you specify how the schedule has changed from year to year. The most you can do is specify one particular schedule—usually the present day schedule—and this is used to convert any date, no matter when.
The third format looks like this:
:characters
Each operating system interprets this format differently; in the GNU C library, characters is the name of a file which describes the time zone.
If the TZ
environment variable does not have a value, the
operation chooses a time zone by default. Each operating system has its
own rules for choosing the default time zone, so there is little we can
say about them.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The array tzname
contains two strings, which are the standard
three-letter names of the pair of time zones (standard and daylight
savings) that the user has selected. tzname[0]
is the name of
the standard time zone (for example, "EST"
), and tzname[1]
is the name for the time zone when daylight savings time is in use (for
example, "EDT"
). These correspond to the std and dst
strings (respectively) from the TZ
environment variable.
The tzname
array is initialized from the TZ
environment
variable whenever tzset
, ctime
, strftime
,
mktime
, or localtime
is called.
The tzset
function initializes the tzname
variable from
the value of the TZ
environment variable. It is not usually
necessary for your program to call this function, because it is called
automatically when you use the other time conversion functions that
depend on the time zone.
The following variables are defined for compatibility with System V
Unix. These variables are set by calling localtime
.
This contains the difference between GMT and local standard time, in
seconds. For example, in the U.S. Eastern time zone, the value is
5*60*60
.
This variable has a nonzero value if the standard U.S. daylight savings time rules apply.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Here is an example program showing the use of some of the local time and calendar time functions.
It produces output like this:
Wed Jul 31 13:02:36 1991 Today is Wednesday, July 31. The time is 01:02 PM.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The alarm
and setitimer
functions provide a mechanism for a
process to interrupt itself at some future time. They do this by setting a
timer; when the timer expires, the process receives a signal.
Each process has three independent interval timers available:
SIGALRM
signal to the process when it expires.
SIGVTALRM
signal to the process when it expires.
SIGPROF
signal to the process when it expires.
You can only have one timer of each kind set at any given time. If you set a timer that has not yet expired, that timer is simply reset to the new value.
You should establish a handler for the appropriate alarm signal using
signal
or sigaction
before issuing a call to setitimer
or alarm
. Otherwise, an unusual chain of events could cause the
timer to expire before your program establishes the handler, and in that
case it would be terminated, since that is the default action for the alarm
signals. @xref{Signal Handling}.
The setitimer
function is the primary means for setting an alarm.
This facility is declared in the header file ‘sys/time.h’. The
alarm
function, declared in ‘unistd.h’, provides a somewhat
simpler interface for setting the real-time timer.
This structure is used to specify when a timer should expire. It contains the following members:
struct timeval it_interval
This is the interval between successive timer interrupts. If zero, the alarm will only be sent once.
struct timeval it_value
This is the interval to the first timer interrupt. If zero, the alarm is disabled.
The struct timeval
data type is described in High-Resolution Calendar.
The setitimer
function sets the timer specified by which
according to new. The which argument can have a value of
ITIMER_REAL
, ITIMER_VIRTUAL
, or ITIMER_PROF
.
If old is not a null pointer, setitimer
returns information
about any previous unexpired timer of the same kind in the structure it
points to.
The return value is 0
on success and -1
on failure. The
following errno
error conditions are defined for this function:
EINVAL
The timer interval was too large.
The getitimer
function stores information about the timer specified
by which in the structure pointed at by old.
The return value and error conditions are the same as for setitimer
.
ITIMER_REAL
This constant can be used as the which argument to the
setitimer
and getitimer
functions to specify the real-time
timer.
ITIMER_VIRTUAL
This constant can be used as the which argument to the
setitimer
and getitimer
functions to specify the virtual
timer.
ITIMER_PROF
This constant can be used as the which argument to the
setitimer
and getitimer
functions to specify the profiling
timer.
The alarm
function sets the real-time timer to expire in
seconds seconds. If you want to cancel any existing alarm, you
can do this by calling alarm
with a seconds argument of
zero.
The return value indicates how many seconds remain before the previous
alarm would have been sent. If there is no previous alarm, alarm
returns zero.
The alarm
function could be defined in terms of setitimer
like this:
unsigned int alarm (unsigned int seconds) { struct itimerval old, new; new.it_interval.tv_usec = 0; new.it_interval.tv_sec = 0; new.it_value.tv_usec = 0; new.it_value.tv_sec = (long int) seconds; if (setitimer (ITIMER_REAL, &new, &old) < 0) return 0; else return old.it_value.tv_sec; }
There is an example showing the use of the alarm
function in
@ref{Handler Returns}.
If you simply want your process to wait for a given number of seconds,
you should use the sleep
function. See section Sleeping.
You shouldn’t count on the signal arriving precisely when the timer expires. In a multiprocessing environment there is typically some amount of delay involved.
Portability Note: The setitimer
and getitimer
functions are derived from BSD Unix, while the alarm
function is
specified by the POSIX.1 standard. setitimer
is more powerful than
alarm
, but alarm
is more widely used.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The function sleep
gives a simple way to make the program wait
for short periods of time. If your program doesn’t use signals (except
to terminate), then you can expect sleep
to wait reliably for
the specified amount of time. Otherwise, sleep
can return sooner
if a signal arrives; if you want to wait for a given period regardless
of signals, use select
(@pxref{Waiting for I/O}) and don’t
specify any descriptors to wait for.
The sleep
function waits for seconds or until a signal
is delivered, whichever happens first.
If sleep
function returns because the requested time has
elapsed, it returns a value of zero. If it returns because of delivery
of a signal, its return value is the remaining time in the sleep period.
The sleep
function is declared in ‘unistd.h’.
Resist the temptation to implement a sleep for a fixed amount of time by
using the return value of sleep
, when nonzero, to call
sleep
again. This will work with a certain amount of accuracy as
long as signals arrive infrequently. But each signal can cause the
eventual wakeup time to be off by an additional second or so. Suppose a
few signals happen to arrive in rapid succession by bad luck—there is
no limit on how much this could shorten or lengthen the wait.
Instead, compute the time at which the program should stop waiting, and
keep trying to wait until that time. This won’t be off by more than a
second. With just a little more work, you can use select
and
make the waiting period quite accurate. (Of course, heavy system load
can cause unavoidable additional delays—unless the machine is
dedicated to one application, there is no way you can avoid this.)
On some systems, sleep
can do strange things if your program uses
SIGALRM
explicitly. Even if SIGALRM
signals are being
ignored or blocked when sleep
is called, sleep
might
return prematurely on delivery of a SIGALRM
signal. If you have
established a handler for SIGALRM
signals and a SIGALRM
signal is delivered while the process is sleeping, the action taken
might be just to cause sleep
to return instead of invoking your
handler. And, if sleep
is interrupted by delivery of a signal
whose handler requests an alarm or alters the handling of SIGALRM
,
this handler and sleep
will interfere.
On the GNU system, it is safe to use sleep
and SIGALRM
in
the same program, because sleep
does not work by means of
SIGALRM
.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The function getrusage
and the data type struct rusage
are used for examining the usage figures of a process. They are declared
in ‘sys/resource.h’.
This function reports the usage totals for processes specified by
processes, storing the information in *rusage
.
In most systems, processes has only two valid values:
RUSAGE_SELF
Just the current process.
RUSAGE_CHILDREN
All child processes (direct and indirect) that have terminated already.
In the GNU system, you can also inquire about a particular child process by specifying its process ID.
The return value of getrusage
is zero for success, and -1
for failure.
EINVAL
The argument processes is not valid.
One way of getting usage figures for a particular child process is with
the function wait4
, which returns totals for a child when it
terminates. @xref{BSD Wait Functions}.
This data type records a collection usage amounts for various sorts of resources. It has the following members, and possibly others:
struct timeval ru_utime
User time used.
struct timeval ru_stime
System time used.
long ru_majflt
Number of page faults.
long ru_inblock
Number of block input operations.
long ru_oublock
Number of block output operations.
long ru_msgsnd
Number of messages sent.
long ru_msgrcv
Number of messages received.
long ru_nsignals
Number of signals received.
An additional historical function for examining usage figures,
vtimes
, is supported but not documented here. It is declared in
‘sys/vtimes.h’.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
You can specify limits for the resource usage of a process. When the process tries to exceed a limit, it may get a signal, or the system call by which it tried to do so may fail, depending on the limit. Each process initially inherits its limit values from its parent, but it can subsequently change them.
The symbols in this section are defined in ‘sys/resource.h’.
Read the current value and the maximum value of resource resource
and store them in *rlp
.
The return value is 0
on success and -1
on failure. The
only possible errno
error condition is EFAULT
.
Store the current value and the maximum value of resource resource
in *rlp
.
The return value is 0
on success and -1
on failure. The
following errno
error condition is possible:
EPERM
You tried to change the maximum permissible limit value, but you don’t have privileges to do so.
This structure is used with getrlimit
to receive limit values,
and with setrlimit
to specify limit values. It has two fields:
rlim_cur
The current value of the limit in question.
rlim_max
The maximum permissible value of the limit in question. You cannot set the current value of the limit to a larger number than this maximum. Only the super user can change the maximum permissible value.
In getrlimit
, the structure is an output; it receives the current
values. In setrlimit
, it specifies the new values.
Here is a list of resources that you can specify a limit for. Those that are sizes are measured in bytes.
RLIMIT_CPU
The maximum amount of cpu time the process can use. If it runs for
longer than this, it gets a signal: SIGXCPU
. The value is
measured in seconds. @xref{Nonstandard Signals}.
RLIMIT_FSIZE
The maximum size of file the process can create. Trying to write a
larger file causes a signal: SIGXFSZ
. @xref{Nonstandard
Signals}.
RLIMIT_DATA
The maximum size of data memory for the process. If the process tries to allocate data memory beyond this amount, the allocation function fails.
RLIMIT_STACK
The maximum stack size for the process. If the process tries to extend
its stack past this size, it gets a SIGSEGV
signal.
@xref{Program Error Signals}.
RLIMIT_CORE
The maximum size core file that this process can create. If the process terminates and a core file is made, and this maximum size is not enough, the core file is truncated.
RLIMIT_RSS
The maximum amount of physical memory that this process should get. This parameter is a guide for the system’s scheduler and memory allocator; the system may give the process more memory when there is a surplus.
RLIMIT_OPEN_FILES
The maximum number of files that the process can open.
If it tries to open more files than this, it gets error code
EMFILE
. @xref{Error Codes}.
RLIM_NLIMITS
The number of different resource limits. Any valid resource
operand must be less than RLIM_NLIMITS
.
This constant stands for a value of “infinity” when supplied as
the limit value in setrlimit
.
Two historical functions for setting resource limits, ulimit
and
vlimit
, are not documented here. The latter is declared in
‘sys/vlimit.h’ and comes from BSD.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
When several processes try to run, their respective priorities determine what share of the CPU each process gets. This section describes how you can read and set the priority of a process. All these functions and macros are declared in ‘sys/resource.h’.
The range of valid priority values depends on the operating system, but
typically it runs from -20
to 20
. A lower priority value
means the process runs more often. These constants describe the range of
priority values:
PRIO_MIN
The smallest valid priority value.
PRIO_MAX
The smallest valid priority value.
Read the priority of a class of processes; class and id specify which ones (see below).
The return value is the priority value on success, and -1
on
failure. The following errno
error condition are possible for
this function:
ESRCH
The combination of class and id does not match any existing process.
EINVAL
The value of class is not valid.
When the return value is -1
, it could indicate failure, or it
could be the priority value. The only way to make certain is to set
errno = 0
before calling getpriority
, then use errno
!= 0
afterward as the criterion for failure.
Read the priority of a class of processes; class and id specify which ones (see below).
The return value is 0
on success and -1
on failure. The
following errno
error condition are defined for this function:
ESRCH
The combination of class and id does not match any existing process.
EINVAL
The value of class is not valid.
EPERM
You tried to set the priority of some other user’s process, and you don’t have privileges for that.
EACCES
You tried to lower the priority of a process, and you don’t have privileges for that.
The arguments class and id together specify a set of processes you are interested in. These are the possible values for class:
PRIO_PROCESS
Read or set the priority of one process. The argument id is a process ID.
PRIO_PGRP
Read or set the priority of one process group. The argument id is a process group ID.
PRIO_USER
Read or set the priority of one user’s processes. The argument id is a user ID.
If the argument id is 0, it stands for the current process, current process group, or the current user, according to class.
Increment the priority of the current process by increment. The return value is not meaningful.
Here is an equivalent definition for nice
:
int nice (int increment) { int old = getpriority (PRIO_PROCESS, 0); setpriority (PRIO_PROCESS, 0, old + increment); }
[Top] | [Contents] | [Index] | [ ? ] |
This document was generated on January 16, 2023 using texi2html 5.0.
The buttons in the navigation panels have the following meaning:
Button | Name | Go to | From 1.2.3 go to |
---|---|---|---|
[ << ] | FastBack | Beginning of this chapter or previous chapter | 1 |
[ < ] | Back | Previous section in reading order | 1.2.2 |
[ Up ] | Up | Up section | 1.2 |
[ > ] | Forward | Next section in reading order | 1.2.4 |
[ >> ] | FastForward | Next chapter | 2 |
[Top] | Top | Cover (top) of document | |
[Contents] | Contents | Table of contents | |
[Index] | Index | Index | |
[ ? ] | About | About (help) |
where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:
This document was generated on January 16, 2023 using texi2html 5.0.